home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d27
/
calctime.arc
/
CALCTIME.DOC
< prev
next >
Wrap
Text File
|
1990-09-15
|
24KB
|
727 lines
┌───────────────────────────────────────────────────┐
│ CALCTIME version 1.2 │
│ │
│ DOS Command Utility Involving Time. │
│ │
│ Reference Manual │
└───────────────────────────────────────────────────┘
Steve Williams
4380 US 29
Tucker, Ga 30084
Copyright 1990. All rights reserved.
This version of Calctime is available as "shareware". Non-registered
users are granted a limited licence to make an evaluation copy for
trail use on a private, non-commercial basis. After evaluating this
software, you should either register your copy or discontinue it's
use. Registration entitles you to private use the software.
Disclaimer
Use of this program acknowledges this disclaimer: "This program is
supplied as is. The author disclaims all warranties, expressed or
implied, including, without limitation, the warranties of
merchantability and of fitness of this program for any purpose. The
author assumes no liability for damages direct, indirect, or
consequential, which may result from the use or misuse of this
program."
Use this program at your own risk.
- 1 -
┌───────────────────┐
│ Table of Contents │
└───────────────────┘
Title page and Disclaimer
Distribution Contents
Introduction
Usage
Errors
Software Information
Registration Form
Distribution Contents
The following files are included in the CALCTIME Package.
CALCTIME.COM
CALCTIME.DOC
Introduction
This utility is similar to David Cusimano's program USETIME.EXE.
Mr. Cusimano did an excellent job on USETIME, but the program does not
perform the work that I required of it. So, I worked up CALCTIME to
replace and remove the limitations of USETIME.
Calctime is capable of not only substituting time parameters in
DOS commands, but of manipulating the time and date as well; there are
also more substitutions available to the user. This utility runs in a
smaller environment, and conserves memory much better than previous
versions.
This program is flexible and is aware of it's true name, if you
rename it, it will inform you of such on the help screen. This is not
a protection scheme, but something I've been playing around with and
working on. Calctime's awareness also has a direct effect on it's use
in conjunction with the environment list.
Read this documentation and try out the program. If you find it to
be useful, please register it for $10(US). By supporting shareware,
you make it possible for shareware products to be produced.
This program should be error free. If you encounter an error, I
will be more than willing to correct the error as soon as possible.
Thank You for your support.
- 2 -
Usage
CalcTime has the following format:
CALCTIME [/switches] (command) [arguments and keys] <cr>
SWITCHES: a few rules to live by... but, switches are optional.
- All switches must appear before the substituting command line.
- All switches are denoted by a slash ("/") in front of each switch.
- Each switch must be separated by at least one space.
- And, switches may not contain any spaces in them.
The following switches directly effect the time and date substitution
keys. All these switches are cumulative in nature.
Y±Σ : adds or subtracts years from the current value.
M±Σ : adds or subtracts months from the current value.
D±Σ : adds or subtracts days from the current value.
H±Σ : adds or subtracts hours from the current value.
I±Σ : adds or subtracts minutes from the current value.
S±Σ : adds or subtracts seconds from the current value.
- "±" denotes a plus(+) or minus(-), for addition and subtraction.
- "Σ" denotes an integer or another substitution key.
An integer I can see, but another substitution key? Here's an
example, what if you are using the current day + the current month for
a dynamic password scheme in some program. Calctime can now be used to
automate that program's execution. Most people will not have use for
Cacltime's ability to add(or subtract) keys with one another, but
someone might, so I included it.
1-7 :
The switches 1-7 are used to change the logical "beginning of the
week" weekday. Does this sound strange? For most of us, the week
begins on Monday (or is it Friday afternoon), but the calender starts
on Sunday, and the motion picture industry begins the week on Friday.
This switch is used to select the beginning weekday for use in
calculating the week number of the year. This switch is designed for
use with business purposes in mind. If you are not going to be using
the "K" key, do not be concerned. If you will be using the "K" key,
please note that this utility assumes the week begins on Sunday. To
change this assumption, use the "1" - "7" switches:
The numbers correspond to days in this fashion:
/1 - Sunday (the default value)
/2 - Tuesday
/3 - Monday
/4 - Wednesday
/5 - Thursday
/6 - Friday
/7 - Saturday
P:
The "P" switch will Print the command line to the standard output
device before executing it.
- 3 -
R:
The "R" switch will cause Calctime to Read the current time (in
absolute seconds since 1970) from the standard input device. There
will be no prompt displayed by Calctime, thus, improper use can hold
up an automated batch file.
This switch can be extremely useful for batch files executing near
a time or date boundary (such as midnight). The R switch causes
Calctime to set the variable clock key (denoted by #) to absolute
seconds in time. This value is read from the standard input device and
is the number of seconds that have elapsed since Jan 1, 1970. This
value can be stored to a file using DOS redirection and the "Z" key.
The general idea is to save a time value to a temporary file, and
then use that file (via DOS redirection) as input to the /R switch. To
save the current time value, use the Z substitution key. The following
example shows this procedure:
CALCTIME echo $z > holdtime { store absolute seconds to temp file }
CALCTIME /r copy c:\daily\files\*.* c:\archive\#m-#d-#y.dat < holdtime
{ use the saved time in the next cmd }
DEL holdtime { delete the temp file after your done with it }
Although this example doesn't really show off /R's usefulness, try to
imagine a batch file that is much longer and occurs just before
midnight. Although it has not been wise to set up a system to do
day-end processing before the midnight barrier, this program does give
you the power and flexibility to do such systems.
E:
The "E" switch tells Calctime to search the Environment for itself
and a set of switches to be substituted at the point where the /E
switch was encountered.
If no environment variable is not found, Calctime will report this
information to the standard output device and will then resume
processing; Calctime does not consider this occurrence to be an error.
Calctime has an ability not mentioned yet, but you need to be
aware of it before using /E switch. Calctime can be renamed (as with
all programs), but Calctime can sense this change and will adapt
itself to this change.
When using the /E switch, Calctime will search the environment
list looking for itself(whatever you've renamed it). The default is
CALCTIME=....
But, if you rename Calctime to CT.COM, this utility will search for
CT=.... in the environment list.
If you're not familiar with the environment list, I suggest you
read your DOS manual, especially the DOS command "SET".
The environment variable is only good with switches. Placing
anything else on the environment line will result in an error message.
Ex: set CALCTIME=/y+1 /m-1 /h+23 {valid: switches only}
set CALCTIME=/y+1 echo the time is $t {invalid: non-switches}
- 4 -
L :
The L switch tells calctime to advance the variable time set to
Last day of the month. This is in conjunction with any other date
manipulations already performed.
Examples:
Calctime /L echo #t <cr>.
This would print the timestamp giving the date as the last day of this
month.
Calctime /m-1 /L echo #t <cr>.
This gives the timestamp date of the last day of last month.
Calctime /l /m-1 echo #t <cr>.
This would give the timestamp with the date of the last day of this
month, but with last month's name. Of course, if this is a 31 day
month, the result will most likely be last month the 30th. Save for
July and February.
Calctime /m-1 /l /d+1 echo #t <cr>.
This will give the timestamp for the beginning of this month. Of
course, other combinations are possible on this theme.
- 5 -
KEYS: what are they and how do they work:
There are currently three keys; the `$' key, the `#' key,
and the `!' key. The first two ($ and #) are time substitution keys as
follows, and the last (!) is a special difference key.
Each one represents a certain date-time variable set used in the
program. The default values for all keys is the current time. If the
/R switch is used, then the `#' key is set to the read in value time.
$: The dollar sign represents the current static time and will not
change through out the program's execution. Any reference to a $
substitution will yield the current clock time of your machine.
#: The pound sign represents the variable time set and is changed by
use of the previously mentioned switches that manipulate the time and
date. This key defaults to the current time if no switches are
encountered. If the /R switch is used, then this key is changed to the
time calculated from the read in value. (This will destroy any
previous time manipulations preceding the /R switch.)
The precedence of the switches is fairly simple in nature. Each
switch is processed from left to right with only one exception, the /R
switch. All time manipulative switches that occur before the /R switch
will be lost, and all the switches after the /R switch will effect the
new variable time set. All the time manipulative switches are
cumulative in nature; however, the /R switch changes the effective
variable time set. So, adding a year before the /R switch will have no
effect of the variable time set(`#' set), it will have the time
calculated from the read in value. Of course, adding a year AFTER the
/R switch will effect the variable time set in the expected manner.
The ! key:
This is the difference key. It calculates the difference between
the $ key and the # key. This is a trivial feature for people who
aspire to be Mr. Spock from Star Trek(copyrighted, Paramount). Or
perhaps it's just for the curious. It is really just an added feature
that might can be useful to help keep track of batch file execution
times, and other stuff like that. In any event, it is only valid with
the following key substitutions:
Y - years portion of the time difference
M - month portion
D - days portion
H - hours portion
M - minutes portion
S - seconds portion
T - combination of ALL the above.
The use that came to mind initially was for it is to display the
time since the beginning of something. An example is the display of
how long Joe's BBS been online at the time of your login (in this
case, a friend of mine is using it for this function). But, more
creative minds than mine should find other deranged and perhaps even
useful purposes for it.
- 6 -
Substitutions:
A: gives the day number of the year (1-366).
B: reports the "beginning of week" day name (Sunday - Saturday).
C: gives full month name (January - December).
D: inserts the date of the month (01 - 31).
E: gives the full year (1970 - 20??).
F: filled with the full day name of the week (Monday - Sunday).
G: hours in the 12 hour notation (01 - 12).
H: hours in the 24 hour notation (00 - 23), military style.
I: minutes (00 - 59).
J: not used (yet).
K: gives the week number of the year based on the value of B (01-53).
L: Last day: gives the date unless it's the last day of the month,
at which it gives "LD", instead (01 - LD).
M: inserts the month number (01 - 12).
N: gives the number of sec.s elapsed since midnight (00000-86399).
O: reports the month in 3 character format (JAN - DEC).
P: not used.
Q: gives the quarter of the year, based on the 3 month cycle (1 - 4).
R: not used.
S: seconds (00 - 59).
T: this gives a full bodied time stamp.
Ex: 10:02 pm, Friday, June 15, 1990
U: not used.
V: not used.
W: this gives the 3 character format day of the week (MON - SUN).
X: reports AM or PM (am - pm).
Y: gives the two digit year number (00 - 99).
Z: this gives the number of sec.s elapsed since Jan. 1, 1970. This
value was chosen since it's the UNIX standard time reference.
$, #, and/or !:
double keys give a single key in the substituted command line to
be executed.
- 7 -
Errors
By overlaying itself, Calctime allows DOS errors to be returned to
the calling program of batch file. Also, if Calctime itself occurs an
error, it returns the error code of 101.
There are about a dozen errors that can occur and be detected.
Some are user related, others are software related. The possible
errors are:
Clock counter warped out of bounds - this error results when you out
step the boundaries of the time modifier switches, like /y-1000; this
will give an error.
DOS command required - Calctime requires a command appear after the
switches. This error will not occur if you give an invalid command.
This only appears in the complete absence of any command parameter.
Ex: CALCTIME /y+3 /h-1 <cr> {no command parameter specified}.
Error #0 does not exist - if you receive this error, then the program
has been hacked by some user. Please report this to me, the
programmer, and discontinue use of this utility.
Improper Spawn Procedure, Contact Programmer - this error should never
occur since it was instantiated for debugging purposes. If it does
occur, the problem is caused by Calctime not being able to properly
create a child process. This is a DOS call related error and could be
caused by a possible DOS incompatibility problem, it might also
represent other serious problems. This error usually occurs when
Calctime cannot find command.com (or what ever you have assigned to
COMSPEC in the environment list).
Invalid Input, value must be a positive integer - you used non-numeric
input on the \R switch input request. Please use only positive numeric
input values.
Invalid operator detected in switch - use only + and - operator in the
time modifying switches. This will only occur during the YMDHIS
switches. This error will not occur if the switch was invalid.
Invalid parameter on environment line - a non-switch parameter was
found on the environment line. Remember, only switches may appear on
the environment line.
Invalid switch in command line - self explanatory. You attempted to
use a switch that is not defined in this program. See switches for a
list of valid switches (they include Y,M,D,H,I,S,P,R, and E).
Not Enough Memory to run spawned file - The dreaded OUT OF MEMORY
error. There's nothing I can do to help you on this one. You should
see about using your available memory more carefully, or run smaller
programs. This error is returned by a DOS call and is out of my
control. Since Calctime overlays itself in memory, it's doing it's
best to conserve memory.
- 8 -
Resulting command line too long - after all substitutions and
modifications have been made to generate the desired executable
command line, the length is greater than 127 characters. The DOS limit
is 128, my limit is 127. Try to shorten you command line. Note If
you're trying to execute a batch file on this erred line, please note
that the effective length is shortened to 116 characters. This was
necessary to conform program to memory conservation standards.
Switch operation too long - a valid switch was encountered, but
contained too many parameters. This error is resultant in the misuse
of the YMDHIS switches.
Switch too long - a switch was found to be longer than allowed. This
error is resultant in the misuse of the ERP switches. These switches
are stand alone and require no parameters.
Third token in switch operation not valid - you used an invalid
substitution key or value in a valid switch (YMDHIS) with a valid
operator.
Unable to create appended child process - attempt to create the child
process failed. Same as Improper Spawning Error(see above).
Unknown error occurred while spawning, Contact Programmer - and yet
one more of these mysterious spawning error detectors. Please see
Improper Spawning error above.
- 9 -
Software Information
This version limits time to the boundaries to an unsigned long
integer. The origin being Jan. 1st, 1970, and the highest allowable
date of about 6:30 am, Feb. 6, 2106. If this utility is still around,
you can bet I've modified it by then to count much, much higher! But
for now, I want to avoid using floating point values, so I used the
largest integer type available. Needless to say, this program just
might out live me, and it's designed to certainly out live all of
today's PC's (they have a limited clock capability stopping at the
year 2100).
I've spent a great deal of time and effort to keep all time and
date manipulations and calculations accurate. This program has been
written to conform to the Gregorian Calendar System created circa
1572, and adopted by the United States of America in 1752. This
program does not take into account the century leap year exception of
this Greg. Cal. System because of it's incidental usage in the 20th
century. Under the Greg. Cal. Sys., centuries not divisible by 4 are
NOT to be leap years. The year 2000 just happens to be one of the leap
centuries. All other calculations should be accurate in their nature.
Pls. contact me if you run across a calculation error. Thanx.
There is a batch file limitation; you can not use the GOTO batch
command with Calctime, as it will not give the desired results.
Example:
calctime GOTO $F
rem the above doesn't execute the GOTO and continues to this line.
goto end
:Saturday
rem this portion is NEVER executed.
:end
rem batch file ends here.
Calctime overlays itself to execute it's command line. This saves
approximately 65K in overall memory usage. Needless to say, if memory
is a problem; this utility should work well for you. If you use
Calctime to run another batch file, there will be about 4K overhead
from a second Command.com (which will be overlaid on top of Calctime's
space). Otherwise, you'll get back all memory used by Calctime. Note:
the second Command.com is necessary for the called batch file to be
able to return to the calling batch file.
This program expands on a "standard" adopted from David Cusimano's
program USETIME.EXE. Calctime.com has been developed specifically to
remove usetime.exe's limitations, as well as serve my own needs for
flexible time variables. I hope you find it to be a useful program.
- 10 -
Send $10(US) Check or Money Order to: Steve Williams
4380 U.S. 29
Tucker, Ga. 30084
Name:___________________________ Company/BBS:_______________________
Address:_____________________________________________________________
City:___________________________ State:_______ Zip:________________
Voice Day Phone:________________ Evening:___________________________
Data/BBS Phone:______________________________________________________
Signature:___________________________________________________________
Comments/Suggestions:________________________________________________
_____________________________________________________________________
_____________________________________________________________________
_____________________________________________________________________
_____________________________________________________________________
- 11 -